---
title: "Quickstart"
description: "Get started with AgentOps in minutes with just 2 lines of code for basic monitoring, and explore powerful decorators for custom tracing."
---

AgentOps is designed for easy integration into your AI agent projects, providing powerful observability with minimal setup. This guide will get you started quickly.

<Check>[Give us a star on GitHub!](https://github.com/AgentOps-AI/agentops) Your support helps us grow. ⭐</Check>

<Note title="Open Source">
The AgentOps app is open source—explore the code in our <a href="https://github.com/AgentOps-AI/agentops/tree/main/app">GitHub app directory</a>.
</Note>

<Note title="Chat with the docs in your IDE">
Prefer asking your IDE? Install the Mintlify <a href="/v2/usage/mcp-docs"><strong>MCP Docs Server</strong></a> for AgentOps to chat with the docs while you code:
`npx mint-mcp add agentops`
</Note>

## Installation
First, install the AgentOps SDK. We recommend including `python-dotenv` for easy API key management.
<CodeGroup>
  ```bash pip 
  pip install agentops python-dotenv
  ```
  ```bash poetry
  poetry add agentops python-dotenv
  ```
  ```bash uv
  uv pip install agentops python-dotenv
  ```
</CodeGroup>

## Initial Setup (2 Lines of Code)

At its simplest, AgentOps can start monitoring your supported LLM and agent framework calls with just two lines of Python code.

1.  **Import AgentOps**: Add `import agentops` to your script.
2.  **Initialize AgentOps**: Call `agentops.init()` with your API key.

<CodeGroup>
```python Python
import agentops
import os
from dotenv import load_dotenv

# Load environment variables (recommended for API keys)
load_dotenv()

# Initialize AgentOps
# The API key can be passed directly or set as an environment variable AGENTOPS_API_KEY
AGENTOPS_API_KEY = os.getenv("AGENTOPS_API_KEY") 
agentops.init(AGENTOPS_API_KEY) 

# That's it for basic auto-instrumentation!
# If you're using a supported library (like OpenAI, LangChain, CrewAI, etc.),
# AgentOps will now automatically track LLM calls and agent actions.
```
</CodeGroup>

### Setting Your AgentOps API Key
You need an AgentOps API key to send data to your dashboard.
- Get your API key from the [AgentOps Dashboard](https://app.agentops.ai/settings/projects).

It's best practice to set your API key as an environment variable.
<CodeGroup>
  ```bash Export to CLI
  export AGENTOPS_API_KEY="your_agentops_api_key_here"
  ```
  ```txt Set in .env file
  AGENTOPS_API_KEY="your_agentops_api_key_here"
  ```
</CodeGroup>
If you use a `.env` file, make sure `load_dotenv()` is called before `agentops.init()`.

## Running Your Agent & Viewing Traces

After adding the two lines and ensuring your API key is set up:
1.  Run your agent application as you normally would.
2.  AgentOps will automatically instrument supported libraries and send trace data.
3.  Visit your [AgentOps Dashboard](https://app.agentops.ai/traces) to observe your agent's operations!


## Beyond Automatic Instrumentation: Decorators

While AgentOps automatically instruments many popular libraries, you can gain finer-grained control and track custom parts of your code using our powerful decorators. This allows you to define specific operations, group logic under named agents, track tool usage with costs, and create custom traces.

### Tracking Custom Operations with `@operation`
Instrument any function in your code to create spans that track its execution, parameters, and return values. These operations will appear in your session visualization alongside LLM calls.
```python
from agentops.sdk.decorators import operation

@operation
def process_data(data):
    # Your function logic here
    processed_result = data.upper()
    # agentops.record(Events("Processed Data", result=processed_result)) # Optional: record specific events
    return processed_result

# Example usage:
# my_data = "example input"
# output = process_data(my_data)
```

### Tracking Agent Logic with `@agent`
If you structure your system with specific named agents (e.g., classes), use the `@agent` decorator on the class and `@operation` on its methods to group all downstream operations under that agent's context.
```python
from agentops.sdk.decorators import agent, operation

@agent(name="MyCustomAgent") # You can provide a name for the agent
class MyAgent:
    def __init__(self, agent_id):
        self.agent_id = agent_id # agent_id is a reserved parameter for AgentOps
        
    @operation
    def perform_task(self, task_description):
        # Agent task logic here
        # This could include LLM calls or calls to other @operation decorated functions
        return f"Agent {self.agent_id} completed: {task_description}"

# Example usage:
# research_agent = MyAgent(agent_id="researcher-001")
# result = research_agent.perform_task("Analyze market trends")
```

### Tracking Tools with `@tool`
Track the usage of specific tools or functions, and optionally associate costs with them. This data will be aggregated in your dashboard.
```python
from agentops.sdk.decorators import tool

@tool(name="WebSearchTool", cost=0.05) # Cost is optional
def web_search(query: str) -> str:
    # Tool logic here
    return f"Search results for: {query}"
    
@tool # No cost specified
def calculator(expression: str) -> str:
    try:
        return str(eval(expression))
    except Exception as e:
        return f"Error: {e}"

# Example usage:
# search_result = web_search("AgentOps features")
# calculation = calculator("2 + 2")
```

### Grouping with Traces (`@trace` or manual)
Create custom traces to group a sequence of operations or define logical units of work. You can use the `@trace` decorator or manage traces manually for more complex scenarios.
<Note>If `auto_start_session=False` in `agentops.init()`, you must use `@trace` or `agentops.start_trace()` for any data to be recorded.</Note>

```python
from agentops.sdk.decorators import trace
# Assuming MyAgent and web_search are defined as above

# Option 1: Using the @trace decorator
@trace(name="MyMainWorkflow", tags=["main-flow"])
def my_workflow_decorated(task_to_perform):
    # Your workflow code here
    main_agent = MyAgent(agent_id="workflow-agent") # Assuming MyAgent is defined
    result = main_agent.perform_task(task_to_perform)
    # Example of using a tool within the trace
    tool_result = web_search(f"details for {task_to_perform}") # Assuming web_search is defined
    return result, tool_result
    
# result_decorated = my_workflow_decorated("complex data processing")

# Option 2: Managing traces manually
# import agentops # Already imported

# custom_trace = agentops.start_trace(name="MyManualWorkflow", tags=["manual-flow"])
# try:
#     # Your code here
#     main_agent = MyAgent(agent_id="manual-workflow-agent") # Assuming MyAgent is defined
#     result = main_agent.perform_task("another complex task")
#     tool_result = web_search(f"info for {result}") # Assuming web_search is defined
#     agentops.end_trace(custom_trace, end_state="Success", end_prompt=f"Completed: {result}")
# except Exception as e:
#     if custom_trace: # Ensure trace was started before trying to end it
#         agentops.end_trace(custom_trace, end_state="Fail", error_message=str(e))
#     raise
```

### Updating Trace Metadata

You can also update metadata on running traces to add context or track progress:

```python
from agentops import update_trace_metadata

# Update metadata during trace execution
update_trace_metadata({
    "operation_name": "AI Agent Processing",
    "processing_stage": "data_validation",
    "records_processed": 1500,
    "user_id": "user_123",
    "tags": ["validation", "production"]
})
```

## Complete Example with Decorators

Here's a consolidated example showcasing how these decorators can work together:
```python
import agentops
from agentops.sdk.decorators import agent, operation, tool, trace
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()
AGENTOPS_API_KEY = os.getenv("AGENTOPS_API_KEY")

# Initialize AgentOps. 
# Set auto_start_session=False because @trace will manage the session.
agentops.init(AGENTOPS_API_KEY, auto_start_session=False, tags=["quickstart-complete-example"])

# Define a tool
@tool(name="AdvancedSearch", cost=0.02)
def advanced_web_search(query: str) -> str:
    # Simulate a more advanced search
    return f"Advanced search results for '{query}': [Details...]"

# Define an agent class
@agent(name="ResearchSpecialistAgent")
class ResearchAgent:
    def __init__(self, agent_id: str):
        self.agent_id = agent_id # This will be used as the agent_id in AgentOps
        
    @operation(name="ConductResearch")
    def conduct_research(self, research_topic: str) -> str:
        # Use the tool within the agent's operation
        search_results = advanced_web_search(f"Deep dive into {research_topic}")
        # Simulate further processing
        analysis = f"Analysis of '{research_topic}': Based on '{search_results}', the key findings are..."
        return analysis

# Define a workflow using the @trace decorator
@trace(name="FullResearchWorkflow", tags=["research", "analysis", "example"])
def run_full_research_workflow(topic: str) -> str:
    specialist_agent = ResearchAgent(agent_id="researcher-alpha-007")
    research_findings = specialist_agent.conduct_research(topic)
    
    final_report = f"Research Report for '{topic}':\n{research_findings}"
    # agentops.record(Events("ReportGenerated", details=final_report)) # Optional: record a custom event
    return final_report

# Execute the workflow
final_output = run_full_research_workflow("AI in healthcare")
print(final_output)
```

## Next Steps

You've seen how to get started with AgentOps! Explore further to leverage its full potential:

<CardGroup cols={2}>
  <Card
    title="Integrations"
    icon="plug"
    href="/v2/integrations"
  >
    See how AgentOps automatically instruments popular LLM and agent frameworks.
  </Card>
  <Card
    title="Examples"
    icon="square-code"
    href="/v2/examples"
  >
    Explore detailed examples for various use cases and integrations.
  </Card>
  <Card title="SDK Reference" icon="book-open" href="/v2/sdk-reference">
    Dive deeper into the AgentOps SDK capabilities and API.
  </Card>
  <Card title="Trace Decorator" icon="code" href="/v2/usage/trace-decorator">
    Learn how to group operations and create custom traces using the @trace decorator.
  </Card>
</CardGroup>

<script type="module" src="/scripts/github_stars.js"></script>
<script type="module" src="/scripts/scroll-img-fadein-animation.js"></script>
<script type="module" src="/scripts/button_heartbeat_animation.js"></script>
<script type="css" src="/styles/styles.css"></script>
<script type="module" src="/scripts/adjust_api_dynamically.js"></script>
